.. |Edit_ic| image:: Img/Edit_ic.png


.. _Руководство по работе со скриптами:

###########################################
Руководство по работе с внешними скриптами
###########################################


**********************************************************
Назначение и общий функционал работы с внешними скриптами
**********************************************************

Скрипты, поддерживаемые приложением располагаются в конфигурационной базе приложения. Внешние js-файлы обычно содержат код, который используется на нескольких
различных веб-страницах. Такие скрипты называются **внешними скриптами**.

Управление скриптами в приложении осуществляется с помощью редактора скриптов см (:numref:`Руководство по настройке скриптов`) Руководства администратора.



Для работы с Системой в коде внешнего скрипта доступны следующие глобальные переменные:

* $getters - все геттеры стора (vuex) приложения.
* $repos - API репозитории (adminRepository, uiRepository и т.п.).
* $plugins - плагины Приложения.

Внешние скрипты используются:

* в Формах
* в компоненте **SmartInput**
* для вычисления ключевых слов (**KEYWORDS**) приложения
* в Actions API



.. _develop_external_scripts:

************************************
Порядок работы с внешними скриптами
************************************

Для импорта внешних скриптов в компоненты Приложения используется плагин "ScriptInjector". 

**Плагин "ScriptInjector"**

Обеспечивает получение, сохранение и выполнение скриптов. Плагин и все его файлы находятся в каталоге /plugins/script-injector.
Приложению доступен единственный метод "$ScriptInjector.inject(<script-id> [,context])".

Порядок работы плагина:

* Скрипт запрашивается из списка доступных скриптов.

* Полученный исходный js-файл внешнего скрипта сохраняется в отдельный динамический vuex-модуль. Последующие запросы по тому же URL возвращают ранее сохраненный скрипт из стора.

* Выполнение внешнего скрипта производится через плагин  "vm-browserify" (плагин для выполнения js-кода в Приложении). Используется локальная (измененная) версия 
  стороннего плагина "vm-browserify". То есть данный плагин берется не из NPM-пакета, а хранится локально в каталоге /plugins/vm-browserify.
  Внешний скрипт выполняется через плагин "vm-browserify" в пределах контекста. 

.. note:: Контекст - это передаваемые в скрипт переменные при его выполнении в плагине "vm-browserify".

Пример внешнего скрипта, в котором происходит обращение к переменным из контекста: ::

        dependency = {
        clickFunction: function (param) {
            return `param to clickFunction was ${param}`
        },
        lang: $getters['auth/language'],
        plugins: $plugins,
        repos: $repos,
        }

  Здесь $getters, $repos, $plugins - это переменные, переданные из контекста.

  Обращение к переменным из контекста означает, что из такого скрипта можно обращаться, например, к бэкенду.

  *Например, в компоненте карты можно запрашивать данные локаций из бэкенда в методе клика по маркеру на карте.*

  Если контекст приложения  не был передан, то используется контекст "по-умолчанию", содержащий геттеры, репозитории и плагины.

  В этом случае используются: 

    * $getters - все геттеры стора (vuex) Приложения. Описание геттеров (см :numref:`Store API Getters` Руководства разработчика)
    * $repos - API репозитории. (см :numref:`Repository API` Руководства разработчика)
    * $plugins - плагины Приложения.

Пример использования плагина "ScriptInjector": ::


    dependency = {
    clickFunction: function (param) {
        return `param to clickFunction was ${param}`
    },
    lang: $getters['auth/language'],
    plugins: $plugins,
    repos: $repos,
    }
    // ...
    // где-то в другом компоненте приложения
    // запросим скрипт c идентификатором 7b425f17-b45a-3929-b904-a38aba3528f7 и вернем результат его выполнения
    let result = await this.$ScriptInjector.inject(`7b425f17-b45a-3929-b904-a38aba3528f7`)

    // inject() вернет объект с двумя свойствами:
    // output - результат выполнения скрипта
    // context - переданный контекст (при необходимости он может быть изменен скриптом)
    console.log(result.output)
    /*
    {
    clickFunction: function (param) {
        return `param to clickFunction was ${param}`
    },
    lang: $getters['auth/language'],
    plugins: $plugins,
    repos: $repos,
    }
    */

**Файлы плагина**

*injector*
 Является основным конфигурационным файлом плагина "ScriptInjector". В нем описывается функционал получения и выполнения скриптов. Возвращает factory-функцию с методами плагина. 
 На вход получает ссылки на инстанс, хранилище и опционально дополнительные свойства для контекста.
*store-module*
 Конфигурационный файл для динамического модуля vuex. Описывает vuex-модуль (методы запроса, хранения скриптов, где хранить и т.п.). Используется конфигурационным файлом "injector".
*mixin*
 Миксин для использования в компонентах. Позволяет компонентам получить доступ к скачанным внешним скриптам. 
*index*
 В этом файле производится дополнение контекста, в котором выполняются скрипты и вставка в инстанс (стандартная процедура для плагинов). Вставка плагина в контекст фронтенда. 
 Здесь в контекст для "vm-browserify" передаются геттеры, плагины и репозитории.

Для использования внешних скриптов компонентом SmartInput к нему необходимо подключить миксин /scipt-injector/mixin и выполнить его с привязкой к свойству, в котором 
перечислены источники скриптов.

Все компоненты полей форм наследуются от компонента Form/Elements/index в котором уже имеется функционал взаимодействия с внешними скриптами, поэтому для использования
внешних скриптов в компонентах форм не требуется специально подключать миксин /scipt-injector/mixin (т.к. он уже включен в их корневой компонент Form/Elements/index).

====================================================
Применение внешних скриптов в компоненте SmartInput
====================================================

Функционал компонента SmartInput конфигурируется несколькими внешними скриптами, указанными в файле pages/feed/config/SmartInput.js.
Все указанные конфигурационные файлы являются обязательными. 

Подробное описание и назначение для каждого скрипта см. здесь :ref:`Руководство по настройке SmartInput`.

================================================
Применение внешних скриптов в компоненте формы
================================================


1. Для использования внешних скриптов в компоненте формы необходимо сначала поместить данные внешние скрипты в реестр (базу) скриптов приложения.
2. Затем в Редакторе форм необходимо открыть нужную форму на редактирование
3. На вкладке "Компоненты" следует найти компонент, для которого предполагается использовать внешние скрипты.
4. Далее необходимо редактировать компонент
5. В открывшейся форме редактирования компонента на вкладке "Параметры"  необходимо написать добавить в json описание параметр "dependencies" следующего формата: ::

    {
    "dependencies": [
        {
        "name": "mapIncidentsHandler",
        "src": "241cc18a-e62a-36d9-8578-76fa468e8f2d"
       },
      {
       "name": "some_other_dependency",
       "src": "190b3f74-36e3-37a1-b34e-bee7d637658a"
      }
     ]
    }

..

Здесь указано следующее: 
         
        *dependencies*
               В квадратных скобках перечисляются все зависимости. Каждая зависимость указывается в фигурных скобках.
        *name*
               Указывается наименование зависимости. В примере указаны две зависимости, их наименования: "mapIncidentsHandler" и "some_other_dependency".
        *src*
               идентификатор скрипта в реестре скриптов.


Подробнее об использовании внешних скриптов компонентами форм см. :ref:`Настройка компонентов шаблона`.

6. После этого необходимо сохранить изменения компонента формы и изменения самой формы по соответствующим кнопкам "Сохранить".

7. Для того, чтобы измнения из внешних скриптов вступили в силу в Системе, достаточно обновить страницу с формой, к компоненту которой были добавлены внешние скрипты. Перезапускать Систему не нужно.

================================================
Примеры использования внешних скриптов в Системе
================================================

**Пример 1.** Использование внешнего скрипта для компонента поля формы с типом "карта" ElMap : ::


    markerCallback({type, group, marker}){
        switch (type) {
            case 'click':
            // TODO: declare callbacks for specific marker groups
            this.dependencies.MAP.markerClickCallback({
                group,
                marker,
                },
                {
                $console:window.console,
                $vm:this
            })
            break;
            default:
            // this.markerDefaultCallback()
            break;
        }
        }

В этом примере компонент использует метод "markerClickCallback" из его зависимости (внешнего скрипта) с названием "MAP".

.. note:: Для остальных компонентов полей формы использование внешних скриптов указывается аналогичным образом.

**Пример 2.** Использование внешнего скрипта в Редакторе форм для компонента формы с типом "map": ::

    {
     "dependencies": [
      {
        "src": "e10802b3-035b-3284-801b-e6d1f5b2695a",
        "name": "MAP"
      }
     ],
     "url": "https://core-renderer-tiles.maps.yandex.net/tiles?l=map&x={x}&y={y}&z={z}&scale=1&lang=ru_RU"
    }

..

Здесь в Редакторе форм в поле "Параметры" указывается структура "dependencies" в формате JSON. В результате компонент формы будет использовать внешний скрипт 
script-inject/form/incidents/map/sites-v2.js. 

.. note:: Для остальных компонентов формы использование внешних скриптов указывается аналогичным образом.


.. _KEYWORDS Script API:

****************************************************************
Описание разработки ключевых слов, с помощью SCRIPT API
****************************************************************


========================================================
Общее описание
========================================================

Для программирования ключевых слов используется скрипт с идентификатором **KEYWORDS**

| Скрипт должен содержать javascript функцию keywords.
| Функция возвращает объект с перечнем поддерживаемых ключевых слов.


Каждое ключевое слово содержит *value*, который может быть функцией или ссылкой (по идентификатору) на другой скрипт, в котором вычисляется значение.



========================================================
Пример
========================================================

 ::

    function keywords (ctx) {
    return {
       RANDOM_STRING: {
        value: 'db3c2509-864c-3b45-894a-75cab412d3da'
      },

      RANDOM_EMOJI: {
         value () {
          const emoji = ['emoji1','emoji2']
          const randomIndex = Math.floor(Math.random() * emoji.length)
           return emoji[randomIndex]
        }
      }
     }
    }

..